Postman como documentar

Postman como herramienta de testing y documentación.

El objetivo de este marco es mostrar las ventajas que se pueden aprovechar de la herramienta Postman como parte de los pasos a seguir al momento de hacer deploy a producción.

Postman como herramienta de documentación.

Postman es un software que nos permite simular las peticiones que se realizan al servidor por parte de nuestra aplicación móvil o página web. Este software nos permite especificar el cuerpo de la petición, queries, headers, tokens, params, etc., con datos que se asemejen lo más posible a peticiones reales de nuestra aplicación. Estas peticiones, utilizadas para testing de nuestro backend, también se pueden convertir rápidamente en un documento online que explique el funcionamiento de nuestro servidor, las peticiones y detalles sobre sus parámetros de entrada.

¿Cómo crear una documentación?

Para crear la documentación de una colección entera, se hace clic en los tres puntos de opciones y posteriormente en el campo "View documentation," el cual abrirá una pestaña con diferentes campos de descripción y una jerarquía de carpetas basada en la organización de nuestras peticiones.

Ejemplo

Este es un ejemplo del archivo de documentación que nos genera Postman. En esta pestaña se pueden agregar descripciones a las peticiones, comentarios a los parámetros y ejemplos de peticiones, de forma que el documento sea lo más claro y enriquecido posible.

• Los detalles de cada petición ayudarán al programador que se incorpore al proyecto, facilitándole la introducción a la aplicación o, incluso, al mismo programador que realice dicha documentación.

• Aunque la documentación está mayormente enfocada hacia el área de programación, este documento puede ser publicado en un enlace público que se comparte con las distintas áreas del proyecto, o simplemente utilizar una forma más accesible de compartir el documento.

Postman como herramienta de Testing.

Además de permitirnos documentar y simular nuestro código, Postman nos brinda la posibilidad de añadir código JavaScript para crear pre-request scripts y test scripts, los cuales nos permiten tener un mayor control sobre lo que se recibe en la petición.

Una de las razones por las cuales se recomienda generar estos scripts al crear la colección es evitar que nuevos cambios en el código, nuevas características o cambios de equipo de trabajo puedan causar fallos en el código que no sean perceptibles a simple vista para el programador. Incluso, se evitan problemas con fragmentos de código que duran largos periodos sin ser usados.

La forma de crear los test y pre-request scripts es abrir o crear la petición con la cual se va a trabajar y hacer clic en la pestaña de pre-request o test, según sea el caso. Estas pestañas se encuentran en la barra de navegación de la vista principal de la petición.

Dentro de la pestaña de test contamos con diferentes opciones que nos sugieren y autocompletan el código de testing que vayamos a escribir. Cabe señalar que el lenguaje con el cual se realizan estos scripts es JavaScript. Al hacer clic en nuestro botón send, además de ejecutar nuestra petición, se aplicará nuestro test a la respuesta. Los resultados de nuestro test los podemos observar en la vista de response, en la pestaña de test results.

Existen dos tipos de scripts:

• Pre-request
• Test

Como su nombre lo indica, uno se ejecuta antes de lanzar la petición, mientras que el otro prueba la respuesta de nuestro servidor. Existe una jerarquía de scripts al ejecutarlos en nuestra colección de Postman: primero se ejecuta desde el nivel más alto de nuestra colección (la misma colección), luego pasa por las carpetas creadas, las peticiones y las respuestas, respetando siempre el pre-request.

Se incluyen diferentes ejemplos de tests que pueden ser aplicados a las peticiones creadas en nuestro servidor. Puedes encontrar ejemplos aquí.